Configuration Guide & JSON Schemas

This document provides a comprehensive specification of the configuration subdirectories, JSON file formats, schema fields, and customization mechanics in Pepvoid Builder.

1. Directory Layout & Profile Roles

All configuration files reside in the configs/ directory:

configs/
├── global_build.json        # Master build manifest (repositories, defaults, services)
├── package_rules.json       # Dynamic package matching and injection rules
├── base_customizations.json # System customization baseline (hostname, timezone, locale)
├── presets/                 # Unified build presets (minimal.json, gaming.json, developer.json)
├── hooks/                   # Lifecycle hook script templates (pre-install, post-install, pre-iso)
├── architectures/           # Target architecture profiles (x86_64.json, rpi-aarch64.json)
├── desktops/                # Desktop environment package bundles (gnome.json, xfce.json)
├── kernels/                 # Kernel package selection profiles (linux-lts.json)
├── bootloaders/             # Bootloader installation profiles (grub.json)
├── packages/                # Modular package bundle profiles (dev-tools.json, gaming.json)
├── services/                # Runit service activation profiles (ssh.json, bluetooth.json)
├── live-users/              # Live environment account profiles (admin.json, guest.json)
├── platforms/               # Single-board hardware platform overrides (pinebookpro.json)
├── assets/                  # Artwork, isolinux configuration templates, GRUB fonts
└── custom_files/            # Overlay file tree copied directly into rootfs at /

2. Master Manifest: `global_build.json`

global_build.json defines the foundational baseline settings for every build.

Complete Annotated Schema

{
  "system": {
    "iso_label": "PEPVOID",
    "workdir_base": "workdir",
    "xbps_cache": "cache/xbps"
  },
  "iso": {
    "compression_type": "xz"
  },
  "initramfs": {
    "compression": "xz"
  },
  "boot_title": "Pepvoid Live",
  "boot_cmdline": "quiet splash live.user=live live.autologin rd.live.overlay.overlayfs=1",
  "splash_image": "configs/assets/data/splash.png",
  "repositories": [
    "https://repo-default.voidlinux.org/current",
    "https://repo-default.voidlinux.org/current/musl",
    "https://repo-default.voidlinux.org/current/aarch64"
  ],
  "custom_repositories": [],
  "customizations": {
    "hostname": "pepvoid-live",
    "timezone": "UTC",
    "locale": "en_US.UTF-8",
    "keymap": "us",
    "users": [
      {
        "name": "live",
        "groups": [
          "wheel",
          "audio",
          "video",
          "storage",
          "network"
        ],
        "password": "live"
      }
    ],
    "services": [
      "dbus",
      "NetworkManager",
      "polkitd",
      "bluetoothd",
      "cupsd",
      "avahi-daemon",
      "sshd",
      "chronyd",
      "alsa",
      "acpid",
      "elogind",
      "wpa_supplicant"
    ]
  },
  "common_desktop_packages": [
    "NetworkManager",
    "alsa-firmware",
    "alsa-pipewire",
    "alsa-utils",
    "avahi",
    "blueman",
    "bluez",
    "dbus",
    "elogind",
    "flatpak",
    "git",
    "nano",
    "pipewire",
    "plymouth",
    "polkit",
    "python3",
    "sudo",
    "vim",
    "wpa_supplicant",
    "xorg"
  ],
  "package_sources": {
    "official": [
      "base-system",
      "vim",
      "git",
      "curl",
      "bash-completion",
      "mtools",
      "gptfdisk",
      "efibootmgr",
      "dosfstools",
      "binutils",
      "xz",
      "device-mapper",
      "dhclient",
      "dracut-network",
      "openresolv"
    ]
  }
}

Key Field Descriptions

system.iso_label: Volume identifier string for the ISO9660 volume (PEPVOID).
system.workdir_base: Base working directory for staging files.
system.xbps_cache: Target directory for cached .xbps binary package archives.
boot_cmdline: Linux kernel boot command-line parameters passed by isolinux/GRUB.
repositories: Official Void Linux XBPS mirror URLs evaluated in order.
customizations.services: List of Runit services enabled by symlinking /etc/sv/<service> into /etc/runit/runsvdir/default/.
customizations.users: Account definitions to create during rootfs provisioning.

3. Architecture Profiles (`configs/architectures/`)

Architecture profiles define specific package lists, repositories, or flags for particular architectures.

Example: `configs/architectures/rpi-aarch64.json`

{
  "architecture": "rpi-aarch64",
  "xbps_arch": "aarch64",
  "engine": "PlatformEngine",
  "repositories": [
    "https://repo-default.voidlinux.org/current/aarch64"
  ],
  "package_sources": {
    "official": [
      "rpi-base",
      "rpi-kernel",
      "raspberrypi-userland"
    ]
  }
}

Wayland-capable desktops use explicit profiles so the X11 variants remain available as a fallback. Use xfce-wayland, kde-wayland, or gnome-wayland when a build should prefer a Wayland session. These profiles include Xwayland for applications that still require X11. The regular xfce, kde, and gnome profiles are unchanged.

4. Desktop Profiles (`configs/desktops/`)

Desktop profiles specify packages required to build a functional graphical desktop environment.

Example: `configs/desktops/xfce.json`

{
  "desktop_environment": "xfce",
  "display_manager": "lightdm",
  "package_sources": {
    "official": [
      "xfce4",
      "xfce4-panel",
      "xfce4-settings",
      "xfce4-session",
      "xfwm4",
      "xfdesktop",
      "thunar",
      "lightdm",
      "lightdm-gtk-greeter",
      "network-manager-applet",
      "pavucontrol"
    ]
  },
  "customizations": {
    "services": [
      "lightdm",
      "dbus",
      "NetworkManager"
    ]
  }
}

4. Package Bundle Profiles (`configs/software/`)

Package profiles allow modular bundle composition across 16 categories (desktop-essentials, dev-tools, filesystems, multimedia, office, gaming, networking, virtualization, graphics, printing, xorg, wayland, internet, custom-user, base, installer). The optional PeppermintOS application profiles are welcome, suggested, pfetch, and software-center.

Automatic Profile Defaults

Both base.json and filesystems.json are loaded automatically by default for all builds to guarantee base system utilities and filesystem driver compatibility (btrfs-progs, xfsprogs, f2fs-tools, ext4, ntfs-3g, exfatprogs, dosfstools, parted, gptfdisk, etc.).

Package Profile JSON Schema (`packages` + `optional_packages`)

All 16 package profile JSON files follow a clean, standardized schema:

{
  "name": "desktop-essentials",
  "description": "Essential desktop GUI utilities, CLI networking tools, media codecs, archive tools, and rich typography",
  "_comment": "Note: Core desktop utilities are active defaults in 'packages'. Additional desktop helpers (Picom, Feh, Dmenu, Rofi) are listed in 'optional_packages' for easy enablement.",
  "packages": [
    "git",
    "curl",
    "wget",
    "octoxbps",
    "gparted",
    "keepassxc",
    "file-roller",
    "zip",
    "unzip",
    "p7zip",
    "unar",
    "tar",
    "zstd",
    "ffmpeg",
    "gst-plugins-base1",
    "gst-plugins-good1",
    "gst-plugins-bad1",
    "gst-plugins-ugly1",
    "gst-libav",
    "font-inter",
    "noto-fonts-ttf",
    "noto-fonts-cjk",
    "noto-fonts-emoji",
    "dejavu-fonts-ttf",
    "liberation-fonts-ttf",
    "font-awesome",
    "cantarell-fonts",
    "ttf-ubuntu-font-family"
  ],
  "optional_packages": [
    "unrar",
    "picom",
    "feh",
    "dmenu",
    "rofi"
  ]
}

5. Runit Service Profiles (`configs/services/`)

Service profiles allow easily toggling background daemons.

Example: `configs/services/ssh.json`

{
  "service_name": "ssh",
  "package_sources": {
    "official": [
      "openssh"
    ]
  },
  "customizations": {
    "services": [
      "sshd"
    ]
  }
}

6. How to Create a Brand New Desktop Profile

To add a new desktop environment profile (e.g. configs/desktops/pantheon.json):

Create configs/desktops/pantheon.json:

{
  "desktop_environment": "pantheon",
  "package_sources": {
    "official": [
      "pantheon-desktop",
      "lightdm",
      "lightdm-pantheon-greeter",
      "gsettings-desktop-schemas"
    ]
  },
  "customizations": {
    "services": [
      "lightdm",
      "dbus"
    ]
  }
}

Validate the configuration:

python3 cli.py x86_64 -d pantheon --check

Build ISO:

sudo python3 cli.py x86_64 -d pantheon --mode real

7. Custom File Management & Scalable Overlays

Pepvoid Builder provides 3 distinct, scalable mechanisms for copying custom files and directories into the target system:

A. Direct Filesystem Overlay (`configs/overlay/`)

The simplest and most scalable method. Any file or directory placed inside configs/overlay/ is automatically discovered and mirrored directly to the target rootfs at / with attributes preserved and ownership normalized:

configs/overlay/etc/motd -> Copied to /etc/motd
configs/overlay/usr/share/backgrounds/wallpaper.png -> Copied to /usr/share/backgrounds/wallpaper.png
configs/overlay/etc/polkit-1/rules.d/50-custom.rules -> Copied to /etc/polkit-1/rules.d/50-custom.rules

You can also pass external overlay directories on the CLI using --include-dir /path/to/my-overlay.

B. Declarative Structured Copy (`configs/base_customizations.json` & `copy_files`)

For granular control over source, destination, file permissions, and ownership, use declarative copy_files arrays in JSON:

{
  "base_copy_files": [
    {
      "source": "samba",
      "destination": "/etc/samba"
    },
    {
      "source": "scripts/my-helper.sh",
      "destination": "/usr/local/bin/my-helper.sh",
      "mode": "0755",
      "owner": "0:0"
    },
    {
      "source": "sudoers.d",
      "destination": "/etc/sudoers.d",
      "mode": "0440"
    }
  ]
}

Automatic Executable Bits: Any file copied into /usr/bin/, /usr/local/bin/, /etc/cron.*, or ending in .sh automatically receives execution permissions (0755).
Automatic Sudoers Security: Any file copied into /etc/sudoers.d/ is automatically restricted to 0440 mode and owned by root:root.

C. Automatic `/etc/skel` to `/home/<user>` Propagation

When copying configuration files or dotfiles to /etc/skel/ (e.g. skel/.config/xfce4/), Pepvoid Builder automatically propagates these files into the home directories of all created users (e.g. /home/live/, /home/void/) and assigns proper user ownership (chown -R <user>:<user>).

8. Presets & Edition Profiles (`configs/presets/`)

Presets define unified, all-in-one edition specifications that configure desktop environments, package bundle combinations, system defaults, services, and repositories simultaneously.

Rescue & Maintenance edition: `configs/presets/rescue-sysadmin.json`

The rescue-sysadmin preset combines the validated XFCE configuration with a focused tool selection and the edition-local Rescue & Maintenance Center. It loads hardware, filesystems and networking, without the full developer, printing or multimedia profiles. XFCE components are selected individually, avoiding the media player and unrelated plugins from its metapackages.

package_sources.official adds recovery utilities such as TestDisk/PhotoRec, GNU ddrescue, Partclone, FSArchiver, GSmartControl, Dislocker and The Sleuth Kit. exclude_packages removes direct requests from the merged official, common and platform package plan. It does not forbid a required dependency: XBPS still resolves dependencies normally. replace_packages retains its existing role for replacement implementations such as XLibre.

exclude_services removes edition-specific service defaults after profiles are merged. The SSH server remains installed but does not start automatically. NetworkManager manages the network without a separately enabled runit wpa_supplicant instance.

The preset copies its launcher, desktop entry, autostart entry and offline workflow notes. 55-rescue-setup.sh runs after the shared desktop overlay and applies only when the edition data is present. It disables removable-media automount in Thunar and replaces the generic Welcome autostart with the Rescue Center. Manual mounts remain possible; this is not a forensic write blocker.

See Rescue & Maintenance for the build command, user workflows, support boundaries and VM acceptance checklist.

Education edition: `configs/presets/education.json`

The Education preset uses XFCE, a modest classroom software core, and an Education-specific Calamares user policy. Its installed user is not added to wheel; Calamares requires a separate root password, disables autologin by default, and the Education Polkit rule uses root for administrative prompts. These settings are scoped to Education and leave other presets unchanged.

The base includes Firefox, LibreOffice, Portuguese spellchecking, GCompris, Tux Paint and typing practice. Add older-student software only when it fits the school’s hardware and lessons, for example:

sudo python3 cli.py x86_64 --preset education \\
  -p education-lower-secondary -p education-upper-secondary \\
  --mode real --output pepvoid-education-secondary-x86_64.iso

See Education Edition plan for the student safety model, supported age pathways, optional groups and test requirements.

Workplace edition: `configs/presets/workplace.json`

The workplace preset is a focused XFCE desktop for office and small-business use. It includes a browser, email client, LibreOffice, PDF reader, spell-checking, password manager, printing/scanning support and an OpenVPN client. It omits the developer, gaming, rescue and general-purpose networking bundles; the SSH server is excluded. Build it with:

sudo python3 cli.py x86_64 --preset workplace --mode real \\
  --output pepvoid-workplace-x86_64.iso

The VPN client and password manager are tools, not a managed enterprise security policy. Organizations should apply their own network, account, encryption and software-update policies after installation.

9. Lifecycle Hooks Engine (`configs/hooks/`)

Lifecycle hooks allow executing custom shell scripts at four deterministic points during the build:

pre-install: Executed outside the chroot before XBPS installs packages.
post-install: Executed directly inside the chroot environment after package installation and service configuration. Ideal for generating custom version tags, modifying /etc/os-release, or cloning custom dotfiles.
pre-iso: Executed outside the chroot before SquashFS or disk image compression.
post-iso: Executed after the final image, tarball, and checksums are generated.

Hook Example (`configs/hooks/post-install.example.sh`):

#!/bin/sh
# Hook executed inside the chroot
echo "=> Branding custom Void build..."
echo "Pepvoid Builder Custom Workstation v1.0" > /etc/void-custom-release
chmod 0644 /etc/void-custom-release

10. Security Actions & Service Conflict Resolution

The system configurator (SystemConfigurator) automatically manages:

RootPasswordAction: Ingests --root-password <pass> or --lock-root; if neither is configured, the root account is locked by default. User accounts without a configured password are also locked rather than assigned a predictable default.
SSHKeyAction: Provisions authorized keys into /root/.ssh/authorized_keys and /home/<live_user>/.ssh/authorized_keys with strict permissions (0700 directory, 0600 file).
Service Conflict Engine: Automatically detects if NetworkManager is enabled and suppresses conflicting standalone services like dhcpcd to prevent race conditions during boot.

Configuration Guide & JSON Schemas

1. Directory Layout & Profile Roles

2. Master Manifest: global_build.json

Complete Annotated Schema

Key Field Descriptions

3. Architecture Profiles (configs/architectures/)

Example: configs/architectures/rpi-aarch64.json

4. Desktop Profiles (configs/desktops/)

Example: configs/desktops/xfce.json

4. Package Bundle Profiles (configs/software/)

Automatic Profile Defaults

Package Profile JSON Schema (packages + optional_packages)

5. Runit Service Profiles (configs/services/)

Example: configs/services/ssh.json